…mat#3)

Evolution of the existing `material: str` attribute on `Compound`
and `Solid` to also accept `pymat.Material` instances, per the
feature request in MorePET/mat#3 from this project's user community.

The existing str tag (used by STEP/STL exporters as an external
tool label) stays accepted — this is a **type widening**, not a
rename. Downstream code using `isinstance(shape.material, str)`
keeps working; new code can do
`isinstance(shape.material, pymat.Material)` to opt into the
richer physics + PBR path.

Changes
-------

- `Compound.__init__`: `material: str | PymatMaterial | None = None`
- `Solid.__init__`: same type widen
- Both docstrings explain the dual meaning + point at the
  `build123d[materials]` extra
- `pyproject.toml`: new `[materials]` optional extra pulling
  `py-materials[pbr]` from the MorePET/mat feature branch (git+https
  pin — to be replaced with a PyPI version pin once py-materials
  2.2.0 ships the `pbr` extra on PyPI, before proposing this PR
  upstream to gumyr/build123d)
- `all` extra now includes `[materials]`
- TYPE_CHECKING-only import of `pymat.Material as PymatMaterial` in
  both `composite.py` and `three_d.py` — build123d has **no runtime
  dependency** on py-materials unless the user installs
  `build123d[materials]`

API collision note
------------------

The existing `Compound.material` / `Solid.material` attribute is
currently used by STEP/STL exporters as a free-form str tag for
downstream tool metadata. The issue author
([MorePET/mat#3](MorePET/mat#3)) may or
may not have been aware of this collision when proposing the
`shape.material = Material(...)` API. The type widen preserves
every existing usage while enabling the new path. If a stricter
resolution is preferred (separate attribute, deprecation path),
that's a conversation for the issue — this PR takes the minimum
invasive route.

End-to-end example
------------------

`examples/pbr_material_pymat.py` demonstrates the full flow:

1. Create a build123d Part (Box minus Cylinder)
2. Create a `pymat.Material` with physics (density, formula, thermal)
   and a rich PBR backend via `threejs_materials.PbrProperties.from_gpuopen(...)`
3. `part.material = steel` — single assignment, both consumers read
   from the same object
4. Print physics (density, molar_mass), geometry-derived mass
   (volume × density), and the Three.js MeshPhysicalMaterial dict
5. `--visual` flag calls `ocp_vscode.show(part)` for live rendering

Verified end-to-end with a local py-materials install:

    === Physics properties (via py-materials) ===
      density:      8.0 g/cm³
      molar mass:   55.85 g/mol
      part volume:  21.99 cm³
      part mass:    175.92 g

    === PBR rendering (Three.js MeshPhysicalMaterial dict) ===
    { "color": [0.75, 0.75, 0.77], "metalness": 1.0, "roughness": 0.35 }

Install
-------

    pip install build123d[materials,ocp_vscode]

or for the lite path (physics + basic PBR scalars, no texture lib):

    pip install build123d py-materials
    # no [pbr] extra → uses the lite in-tree pymat PBRProperties

Draft / exploratory
-------------------

This branch and PR are exploratory — pending design direction on
MorePET/mat#3 from @gumyr and @bernhard-42. Not ready to merge
upstream until:

- py-materials' `feature/3-pbr-protocol-integration` (MorePET/mat#30)
  lands on dev and ships as py-materials 2.2.0 on PyPI
- The `materials` optional-dependency pin is switched from
  git+https to a PyPI version (`py-materials[pbr]>=2.2.0`)
- Collision + type-widening approach is reviewed by @gumyr

When a `pymat.Material` carries a rich `pbr_source` (a
`threejs_materials.PbrProperties` instance, typically set via
`material.pbr_source = PbrProperties.from_gpuopen(...)`),
`_extract_materials_from_node` now bypasses the field-by-field
projection through the lite `pymat.properties.pbr` dataclass and
uses the rich source directly.

## Why

`py-materials`' lite `PBRProperties` dataclass has no
`base_color_map` / albedo / color texture field. Before this
change, the `is_pymat(node.material)` branch would call
`PbrProperties.create(..., normal_map=..., roughness_map=...,
metalness_map=..., ao_map=...)` and silently drop the color
texture. For materials whose visual identity lives in the color
map (wood, bricks, tiles, stone — most non-metal MaterialX
libraries on matlib.gpuopen.com, polyhaven.com, ambientcg.com),
this made them render as flat white meshes even with a valid
`pbr_source` assigned.

Verified locally with `gpuopen/Ivory Walnut Solid Wood`:

- `part.material = PbrProperties.from_gpuopen("Ivory Walnut Solid Wood")`
  renders with full wood grain (takes the
  `isinstance(node.material, PbrProperties)` fast path).
- `part.material = pymat.Material(..., pbr_source=<same PbrProperties>)`
  previously rendered as flat white (lossy field copy dropped the
  color map). With this change, it now renders identically to the
  direct assignment.

## Design

The fix is 1 conditional + 2 lines: prefer `pbr_source` when set,
fall back to the field-by-field copy when not. Materials without
a rich source (TOML-authored, lite-only) continue to work exactly
as before — backward compatible.

The rich source path also picks up every Three.js
MeshPhysicalMaterial scalar that py-materials' lite dataclass
doesn't model (sheen, anisotropy, iridescence, dispersion,
clearcoat maps, specular intensity/color, thickness, displacement,
specular tinting). These were previously unreachable through the
pymat path.

## Context

Part of an ongoing collaboration between `gumyr/build123d`,
`MorePET/mat` (py-materials), and `bernhard-42/threejs-materials`
to make `shape.material = pymat.Material(...)` the canonical
carrier type in build123d (both physics values and PBR rendering).

- `MorePET/mat#3` — design discussion
- `MorePET/mat#30` — py-materials PR adding `Material.pbr_source`
- `gumyr/build123d#1276` — build123d PR widening
  `Compound/Solid.material` type
- `MorePET/mat`'s ADR-0002 — architectural rationale for the
  Protocol + optional-extra approach

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>